Objective

Introduces a new utility feature; functions for packing and unpacking two numbers into and from a single 64-bit integer representation.

Solution

• Due to JavaScript's limitation of representing all numbers as double-precision floating-point values and its 32-bit limit on bitwise operations, a mathematical approach was taken.
• The solution uses multiplication, division, and exponentiation to simulate the packing and unpacking of two 32-bit numbers into a single 64-bit integer value.
• This approach allows for handling numbers larger than 32 bits, with the caveat that the effective range is limited by JavaScript's safe integer precision (up to 2^53).

Showcase

The new functions can be used to encode/decode two numbers for storage or transmission.

Packing two numbers:

const low = 123456789;   // Represents the lower 32 bits
const high = 654321;  // Represents the higher 32 bits

const packedValue = packInto64Int(low, high);
console.log(packedValue); // Outputs a single large number: 42420001565530885

Unpacking the number:

const [originalLow, originalHigh] = unpackFrom64Int(packedValue);
console.log(originalLow, originalHigh); // Outputs: 123456789, 654321

Migration guide

This is a new feature addition and introduces no breaking changes to the existing API. No migration is required for existing users.

Checklist

• My change requires a change to the documentation.
• I have updated the documentation accordingly. (Documentation is included as JSDoc comments in the new source file)
• I have added tests to cover my changes.